Improve readme to get started with plotly.js JSON interface for non-JavaScript developers and adjust dist/README #5705
Conversation
README.md
Outdated
|
|
||
| ### Install with npm | ||
|
|
||
| ## Load from npm |
There was a problem hiding this comment.
I would have this be first
README.md
Outdated
| * [Notable contributors](#creators) | ||
| * [Copyright and license](#copyright-and-license) | ||
|
|
||
| --- | ||
| ## Quick start options | ||
| ## Load from CDN |
There was a problem hiding this comment.
I would spell out "Content Delivery Network (CDN)"
README.md
Outdated
| ## Load from CDN | ||
| Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>. | ||
|
|
||
| ### Minified plotly.js X.Y.Z bundles |
There was a problem hiding this comment.
I would rename this "Usage example"
README.md
Outdated
| <script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.js" charset="utf-8"></script> | ||
| ``` | ||
|
|
||
| #### Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version. |
There was a problem hiding this comment.
for little "notes" like this, please don't use #### but rather prefix them with > so they get indented/dimmed a bit.
README.md
Outdated
|
|
||
| [Latest and rc releases on GitHub](https://github.com/plotly/plotly.js/releases/) | ||
| --- | ||
| ## Versioning |
There was a problem hiding this comment.
This probably doesn't need to be a top-level item, just a little note somewhere, maybe under the NPM section. it's kind of the norm anyway.
|
Looks better, but why is the MathJax section under Documentation? |
|
I'd put it in the CDN section I think |
README.md
Outdated
| <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script> | ||
| <script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script> | ||
| ``` | ||
|
|
||
| ## Partial bundles | ||
|
|
||
| There are two kinds of plotly.js partial bundles: |
There was a problem hiding this comment.
could we maybe define what a partial bundle is and why we talk about them?
README.md
Outdated
| 1. The official partial bundles that are distributed to `npm` and the CDN, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md). | ||
| ## Bundles | ||
| There are two kinds of plotly.js bundles: | ||
| 1. Complete and partial official bundles that are distributed to `npm` and the `CDN`, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md). | ||
| 2. Custom bundles you can create yourself, if none of the distributed packages meet your needs. |
There was a problem hiding this comment.
I think this custom-bundles section could live in its own separate file, which would be linked to from here (and then all three of dist/custom-bundles/building readmes would link to each other as they are essentially alternative ways of doing similar things)
|
The BUILDING.md file doesn't really provide a decent motivation for why you'd want to build Plotly.js into your library or explain the modules concept etc... Can we take some of what used to be in "modules" in the main readme and transplant it into Building please? Basically show folks how they can directly import parts of Plotly into their app (a) and then if they import modules that require special webpack/"ify"-handling, tell them how to do it? Because if someone wants to build their own app, with just the bar-chart bundle imported directly, they don't need all the "ify" stuff, right? |
archmoj
changed the title
|
OK. There are still things that we could improve with the READMEs. |
|
This all looks good to me, but you've got @nicolaskruchten's comments here, wouldn't it be easier to just address the last couple in this PR and be done with it? |
The diff is already big and we want to move more lines to new files. |
|
new |
|
💃 |
@plotly/plotly_js